  SMB3 Music Inserter
---------------------
2009/11/11 - beta 1.1
by JaSp
jaspile/hotmail/com

SMB3Song XML format
===================

The patches will change the format of RAM address $4F5, used by the game to load songs.

.smb3song files are actually XML files.
Currently, there isn't any XML validation check in the utility, so if you load an
incorrect XML song or if you made an error writting it, the utility will likely
crash.

This text file aims to explain the format and its restrictions to avoid errors,
it assumes that you have basic knowledge of XML.

Root
====
The root node is <song>, it should always be there and only once.


Meta-data
=========
The following nodes are <title>,<author>,<date>,<version>,<comments>; they should
always be in this order, and they may contain any string data (i.e. there are no
checks for a valid date or version format for instance).
You can leave them blank, the editor will just show an "N/A" in the corresponding
song informations field.

Data
====
Then is the <data> node, which contains everything that will be parsed into hex game
data.
It contains two nodes : <parts> and <sequence>.

<parts> is composed of one or more <part> nodes.

A <part> node will be parsed into a chunk of music data that can be played once or more
during a song. It has a required attribute tempo, which has to be set as multiples of
ten (for instance 30,40,etc.; 50 being the most common); experiment with the game to
hear the different tempos. I'm not quite sure wether lower values such as 10 or 20 will
work properly.
The <part> node should contain the following nodes in the correct order :
<square1>,<square2>,<triangle>,<noise>,<dmc>
A <part> can have an optionnal <comments> with whatever you want written in it; although
it is currently not used in the utility.

The <sequence> node should only appear once, it determines in which order and how many
times parts should be played.
The loop attribute is required; it determines which part relative to the _sequence_
should the song loop to (for instance, to have an intro part).

Tracks
======
They correspond to the actual different NES tracks :

<square1> generally is the leading melody; it controls the total duration of the part;
that means that if other tracks are musically longer than this one, you won't hear
them in totality.
It can have an optionnal attribute which define the instrument used, proper values
are 8,9,A,B,C,D,E,F. The default instrument is 9.
Experiment with the game to hear all different instruments.

<square2> generally is used as harmonics.
As square1, it can have an optionnal attribute which define the instrument used, proper
values are 8,9,A,B,C,D,E,F. The default instrument is 9.
Experiment with the game to hear all different instruments.
Be careful as the game may crash/glitch if the duration isn't at least as long as
square1 (track isn't looped).

<triangle> generally is used as the bass instrument. It doesn't have other instruments.
Its notes are maintained as long as you don't define other notes; that means that if in
your score you have twice the same note in a row, you won't hear a brief break silence
as if the note was pressed again. To achieve such an effect, you'll need to place a
silent note ("_") between the two notes.
Be careful as the game may crash/glitch if the duration isn't at least as long as
square1 (track isn't looped).

<noise> is used as light rhythm sounds, i.e. equivalents of hi-hats. Depending on the
value, a different sound will be produced. Experiment with the game to hear all the
different sounds. I still need to provide a reference for a future release.
This track is looped if it reaches the end, so you don't have to cover the whole part
duration.

<dmc> is used as strong rhythm sounds, i.e. kicks and snares. Depending on the value,
a different sound will be produced. Experiment with the game to hear all the different
sounds. I still need to provide a reference for a future release.
This track is looped if it reaches the end, so you don't have to cover the whole part
duration.

Scores format
=============
See "note reference.txt" to see which values are accepted for durations, notes and sounds.

The note sequences are defined as simple text, and should be written as following :

square1,square2,triangle :
--------------------------
A note is defined as such :
D-N or N
L: duration of the note
N: actual note
Example : 4-c#4

Notes should be separated with commas ",".
If you don't define a duration for the note, the previously set duration will be used.
Example : 4-c#4,d4,2-c5,c#5
Here, d4 will have a duration of 4, whereas c#5 will have a duration of 2

noise,dmc
---------
A rhythm sound is defined as such :
D-V or V
L: duration of the note
V: hex value
Example : 4-1

Sounds should be separated with commas ",".
If you don't define a duration for the sound, the previously set duration will be used.
Example : 4-1,4-2

=============
I think I covered almost everything here, however I strongly recommend that you open one
of the provided .smb3song files with a text or XML editor to better understand the format.
